Changes Analysis

Commit SHA: de7fd22
Comparing To SHA: 3441e2b

API Changes

Summary

├─┬Paths
│ ├──[➖] path (2932:3)❌ 
│ ├──[➖] path (2912:3)❌ 
│ └──[➕] path (2912:3)
└─┬Components
  └──[➕] parameters (18927:7)

• ❌ BREAKING Changes: 2 out of 4
• Removals: 2
• Additions: 2
• Breaking Removals: 2

Report

The full API changes report is available at: https://github.com/opensearch-project/opensearch-api-specification/actions/runs/9947904959/artifacts/1704051538

API Coverage

This will cause a breaking change in the clients. The clients accepts both metric and node_id as params for client.nodes.info() function (js, ruby) and uses the following logic to determine which path to use:

• both metric and node_id are provided: /nodes/{node_id}/{metric}
• only node_id is provided: /nodes/{node_id}
• only metric is provided: /nodes/{metric}
• neither is provided: /nodes

This is another quirk of OpenSearch API.
The server treats/nodes/{node_id} and /nodes/{metric} as an identical endpoint. So this endpoint is actually /nodes/{node_id_or_metric}. But this will cause the generated clients to read node_id_or_metric as the 3rd path param. We can collapse those 2 endpoints into /nodes/{node_id_or_metric} but we will have to add a new x- extension to tell the generator how to handle this edge case.

I'm thinking x-union-param: ['node_id', 'metric'] for the node_id_or_metric path param

I'm thinking x-union-param: ['node_id', 'metric'] for the node_id_or_metric path param

I made the change by introducing /_nodes/{node_id_or_metric}.

I am not sure we're doing the right thing by introducing parameter hints where we try to express that this parameter is actually 2 different possible types. As written in this PR the parameter is node_id_or_metric, and it can now be an array of either a node_id or a metric via schema (anyOf). Perhaps, the right way is for clients to patch this behavior to be backwards compatible instead of the spec requiring a hint, or even examine the type and notice that it can be 1 of 2 things?

We should update https://github.com/opensearch-project/opensearch-api-specification/blob/main/CLIENT_GENERATOR_GUIDE.md to alert devs about this edge case as well.

We should update https://github.com/opensearch-project/opensearch-api-specification/blob/main/CLIENT_GENERATOR_GUIDE.md to alert devs about this edge case as well.

Done, d4f3a55.